home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / audiofile / afSetChannelMatrix.z / afSetChannelMatrix
Encoding:
Text File  |  2002-10-03  |  9.0 KB  |  199 lines
  1.  
  2.  
  3.  
  4. aaaaffffSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllMMMMaaaattttrrrriiiixxxx((((3333ddddmmmm))))                                aaaaffffSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllMMMMaaaattttrrrriiiixxxx((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      afSetChannelMatrix - set the channel mix matrix associated with a given
  10.      track in an AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiiooooffffiiiilllleeee....hhhh>>>>
  14.  
  15.      iiiinnnntttt aaaaffffSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllMMMMaaaattttrrrriiiixxxx((((AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee ffffiiiilllleeee,,,, iiiinnnntttt ttttrrrraaaacccckkkk,,,, ddddoooouuuubbbblllleeee**** mmmmaaaattttrrrriiiixxxx))))
  16.  
  17. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR
  18.      _f_i_l_e     is an AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee structure, previously created by a call to
  19.               aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(3dm) or its equivalent.
  20.  
  21.      _t_r_a_c_k    is an integer which identifies an audio track in _h_a_n_d_l_e.
  22.  
  23.               Since all currently supported file formats contain only one
  24.               audio track, the value AAAAFFFF____DDDDEEEEFFFFAAAAUUUULLLLTTTT____TTTTRRRRAAAACCCCKKKK should always be used
  25.               here for now.
  26.  
  27.      _m_a_t_r_i_x   is an array of double precision floating point values which
  28.               specify the manner in which a channel conversion operation
  29.               should take place.  Because the values in this array will be
  30.               copied into internal memory, _m_a_t_r_i_x may be either a locally
  31.               declared array or a dynamically allocated one, and in the latter
  32.               case may be freed immediately after the function call.
  33.  
  34. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  35.      aaaaffffSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllMMMMaaaattttrrrriiiixxxx(((()))) allows an application to specify the exact file to
  36.      virtual mapping, i.e., how nnnn audio file channels should be mapped into mmmm
  37.      buffer channels.  The matrix should be declared as a single-dimension
  38.      array, but should be laid out as if it were a two-dimensional array with
  39.      rows equal to virtual channels and columns equal to file channels.  Note
  40.      that this means that for any given channel conversion, i.e., 2 -> 4, 4 ->
  41.      1, etc., the matrix must be swapped rows-for-columns if you call
  42.      aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss(3dm) instead of aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss(3dm) because the virtual
  43.      format becomes the input rather than the output of the process.
  44.  
  45.      A channel conversion operation will occur any time nnnn != mmmm. This will
  46.      happen during calls to aaaaffffRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss(3dm) or aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss(3dm) when the
  47.      _v_i_r_t_u_a_l channel count has been set to a different value than the _t_r_a_c_k
  48.      channel count (they will always default to the same value).  No matrix
  49.      operation will occur if nnnn == mmmm even if a matrix has been specified.
  50.  
  51.      If no call to aaaaffffSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllMMMMaaaattttrrrriiiixxxx(((()))) is made, or if it is called with
  52.      _m_a_t_r_i_x set to NULL, the AF will revert to a set of default matrices.
  53.      These were designed to match the default matrices used by the Audio
  54.      Library (see AAAALLLLiiiinnnnttttrrrroooo(3dm)).
  55.  
  56.      aaaaffffSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllMMMMaaaattttrrrriiiixxxx(((()))) must be called _a_f_t_e_r the call to
  57.      aaaaffffSSSSeeeettttVVVViiiirrrrttttuuuuaaaallllCCCChhhhaaaannnnnnnneeeellllssss(3dm).  Otherwise, a subsequent call to
  58.      aaaaffffSSSSeeeettttVVVViiiirrrrttttuuuuaaaallllCCCChhhhaaaannnnnnnneeeellllssss will cause the matrix be reset to NULL.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaaffffSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllMMMMaaaattttrrrriiiixxxx((((3333ddddmmmm))))                                aaaaffffSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllMMMMaaaattttrrrriiiixxxx((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  75.      To pan a monaural audio signal buffer to the center of a stereo output
  76.      file:
  77.  
  78.      double matrix[] = { .71, .71 } /* "equal power" stereo */
  79.      int bufferChannels = 1;  /* virtual (buffer) format */
  80.      AFfilesetup setup = afNewFileSetup();
  81.      AFfilehandle handle;
  82.      /* initialize file channel count to stereo */
  83.      afInitChannels(setup, AF_DEFAULT_TRACK, 2);
  84.      handle = afOpenFile("mysoundfile.aiff", "w", setup);
  85.      afSetVirtualChannels(handle, AF_DEFAULT_TRACK, bufferChannels);
  86.      afSetChannelMatrix(handle, AF_DEFAULT_TRACK, matrix);
  87.      /* note that
  88.      afWriteFrames(...);
  89.  
  90.      To read a four-channel file into a stereo buffer with the front channels
  91.      mixed into the far left and right and the back channels mixed into the
  92.      near left and right:
  93.  
  94.      double matrix[] = {
  95.  
  96.      /*       inputs        */
  97.      /*  FL   FR   BL   BR  */
  98.                                /* outputs */
  99.          1.0, 0.0, 0.6, 0.4    /*    L    */
  100.          0.0, 1.0, 0.4, 0.6    /*    R    */
  101.  
  102.      };
  103.      AFfilehandle handle;
  104.      int bufferChannels = 2;  /* virtual (buffer) format */
  105.      /* open 4-channel sound file */
  106.      handle = afOpenFile("4channelsound.aiff", "r", NULL);
  107.      afSetVirtualChannels(handle, AF_DEFAULT_TRACK, bufferChannels);
  108.      afSetChannelMatrix(handle, AF_DEFAULT_TRACK, matrix);
  109.      afReadFrames(...);
  110.  
  111.      To write a four-channel buffer into a stereo file with the same mixdown:
  112.  
  113.      double matrix[] = {
  114.  
  115.       /* outputs */
  116.       /* L    R  */
  117.                         /* inputs */
  118.          1.0, 0.0,      /*   L    */
  119.          0.0, 1.0,      /*   R    */
  120.          0.6, 0.4       /*   BL   */
  121.          0.4, 0.6       /*   BR   */
  122.  
  123.      };
  124.      int bufferChannels = 4;  /* virtual (buffer) format */
  125.      AFfilesetup setup = afNewFileSetup();
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. aaaaffffSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllMMMMaaaattttrrrriiiixxxx((((3333ddddmmmm))))                                aaaaffffSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllMMMMaaaattttrrrriiiixxxx((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.      AFfilehandle handle;
  141.      /* initialize file channel count to stereo */
  142.      afInitChannels(setup, AF_DEFAULT_TRACK, 2);
  143.      handle = afOpenFile("stereosound.aiff", "w", setup);
  144.      afSetVirtualChannels(handle, AF_DEFAULT_TRACK, bufferChannels);
  145.      afSetChannelMatrix(handle, AF_DEFAULT_TRACK, matrix);
  146.      afWriteFrames(...);
  147.  
  148.      Note that the AF always assumes the 4-channel input has its channels laid
  149.      out:
  150.  
  151.                            Front
  152.                          0       1
  153.  
  154.  
  155.                          2       3
  156.                             Back
  157.  
  158. CCCCAAAAVVVVEEEEAAAATTTTSSSS
  159.      The Audio File Library has no way to check the size of the double* array
  160.      passed in to aaaaffffSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllMMMMaaaattttrrrriiiixxxx(((()))).  Care must be taken to assure that the
  161.      array has (in_channels * out_channels) elements, regardless of how the
  162.      data in these channels is to be treated.  Also note the above paragraph
  163.      concerning the calling order of this function.
  164.  
  165. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  166.      afSetVirtualChannels(3dm), afGetVirtualChannels(3dm), afReadFrames(3dm),
  167.      afWriteFrames(3dm)
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.